﻿using System;
using System.Text;
namespace Kyoh.Lib.IO.Archive
{
    /// <summary>Zipファイルのファイル名のエンコード変換を行うインターフェース。</summary>
    public interface IZipConverter
    {
        /// <summary>指定した文字配列に格納されているすべての文字をエンコードすることによって生成されるバイト数を計算します。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="chars">エンコード対象の文字を格納している文字配列。</param>
        /// <returns>指定した文字配列に格納されているすべての文字をエンコードすることによって生成されるバイト数。</returns>
        /// <exception cref="ArgumentNullException"><paramref name="chars"/> が <c>null</c> です。</exception>
        /// <exception cref="EncoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="EncoderFallback"/> が <see cref="EncoderExceptionFallback"/> に設定されています。 </exception>
        int GetByteCount(bool utf8Entry, char[] chars);
        
        /// <summary>指定した文字配列に格納されている文字のセットをエンコードすることによって生成されるバイト数を計算します。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="chars">エンコード対象の文字のセットを格納している文字配列。</param>
        /// <param name="index">エンコードする最初の文字のインデックス。</param>
        /// <param name="count">エンコードする文字数。</param>
        /// <returns>指定した文字をエンコードすることによって生成されるバイト数。</returns>
        /// <exception cref="ArgumentNullException"><paramref name="chars"/> が <c>null</c> です。</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> または <paremref name="count"/> が <c>0</c> 未満です。 または <paramref name="index"/> および <paramref name="count"/> が <paramref name="chars"/> 内の有効な範囲を示していません。</exception>
        /// <exception cref="EncoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="EncoderFallback"/> が <see cref="EncoderExceptionFallback"/> に設定されています。 </exception>
        int GetByteCount(bool utf8Entry, char[] chars, int index, int count);

        /// <summary>指定した<see cref="String"/> に含まれる文字をエンコードすることによって生成されるバイト数を計算します。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="s">エンコード対象の文字のセットを格納している<see cref="String"/>。</param>
        /// <returns>指定した文字をエンコードすることによって生成されるバイト数。</returns>
        /// <exception cref="ArgumentNullException">s が <c>null</c> です。</exception>
        /// <exception cref="EncoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="EncoderFallback"/> が <see cref="EncoderExceptionFallback"/> に設定されています。 </exception>
        int GetByteCount(bool utf8Entry, string s);

        /// <summary>指定したバイト配列に格納されているすべてのバイトをデコードすることによって生成される文字数を計算します。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="bytes">デコード対象のバイト シーケンスが格納されたバイト配列。</param>
        /// <returns>指定したバイト シーケンスをデコードすることによって生成される文字数。</returns>
        /// <exception cref="ArgumentNullException"><paremref name="bytes"/> が <c>null</c> です。</exception>
        /// <exception cref="DecoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="DecoderFallback"/> が <see cref="DecoderExceptionFallback"/> に設定れています。 </exception>
        int GetCharCount(bool utf8Entry, byte[] bytes);
        
        /// <summary>指定したバイト配列に格納されているバイト シーケンスをデコードすることによって生成される文字数を計算します。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="bytes">デコード対象のバイト シーケンスが格納されたバイト配列。</param>
        /// <param name="index">デコードする最初のバイトのインデックス。</param>
        /// <param name="count">デコードするバイト数。</param>
        /// <returns>指定したバイト シーケンスをデコードすることによって生成される文字数。</returns>
        /// <exception cref="ArgumentNullException"><paremref name="bytes"/> が <c>null</c> です。</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> または <paremref name="count"/> が <c>0</c> 未満です。 または <paramref name="index"/> および <paramref name="count"/> が <paramref name="bytes"/> 内の有効な範囲を示していません。</exception>
        /// <exception cref="DecoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="DecoderFallback"/> が <see cref="DecoderExceptionFallback"/> に設定れています。 </exception>
        int GetCharCount(bool utf8Entry, byte[] bytes, int index, int count);

        /// <summary>指定した文字配列に格納されているすべての文字をバイト シーケンスにエンコードします。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="chars">エンコード対象の文字を格納している文字配列。</param>
        /// <returns>指定した文字のセットをエンコードした結果を格納しているバイト配列。</returns>
        /// <exception cref="ArgumentNullException"><paramref name="chars"/> が <c>null</c> です。</exception>
        /// <exception cref="EncoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="EncoderFallback"/> が <see cref="EncoderExceptionFallback"/> に設定されています。 </exception>
        byte[] GetBytes(bool utf8Entry, char[] chars);

        /// <summary>指定した文字配列に格納されている文字のセットをバイト シーケンスにエンコードします。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="chars">エンコード対象の文字のセットを格納している文字配列。</param>
        /// <param name="index">エンコードする最初の文字のインデックス。</param>
        /// <param name="count">エンコードする文字数。</param>
        /// <returns>指定した文字のセットをエンコードした結果を格納しているバイト配列。</returns>
        /// <exception cref="ArgumentNullException"><paramref name="chars"/> が <c>null</c> です。</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> または <paremref name="count"/> が <c>0</c> 未満です。 または <paramref name="index"/> および <paramref name="count"/> が <paramref name="chars"/> 内の有効な範囲を示していません。</exception>
        /// <exception cref="EncoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="EncoderFallback"/> が <see cref="EncoderExceptionFallback"/> に設定されています。 </exception>
        byte[] GetBytes(bool utf8Entry, char[] chars, int index, int count);

        /// <summary>指定した<see cref="String"/> に含まれるすべての文字をバイト シーケンスにエンコードします。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="s">/ <returns>指定した文字のセットをエンコードした結果を格納しているバイト配列。</returns></param>
        /// <returns>指定した文字のセットをエンコードした結果を格納しているバイト配列。</returns>
        /// <exception cref="ArgumentNullException"><paramref name="s"/> が <c>null</c> です。</exception>
        /// <exception cref="EncoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="EncoderFallback"/> が <see cref="EncoderExceptionFallback"/> に設定されています。 </exception>
        byte[] GetBytes(bool utf8Entry, string s);

        /// <summary>指定したバイト配列に格納されているすべてのバイトを文字のセットにデコードします。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="bytes">デコード対象のバイト シーケンスが格納されたバイト配列。</param>
        /// <returns>指定したバイト シーケンスのデコード結果が格納された文字配列。</returns>
        /// <exception cref="ArgumentNullException"><paremref name="bytes"/> が <c>null</c> です。</exception>
        /// <exception cref="DecoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="DecoderFallback"/> が <see cref="DecoderExceptionFallback"/> に設定れています。 </exception>
        char[] GetChars(bool utf8Entry, byte[] bytes);

        /// <summary>指定したバイト配列に格納されているバイト シーケンスを文字のセットにデコードします。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="bytes">デコード対象のバイト シーケンスが格納されたバイト配列。</param>
        /// <param name="index">デコードする最初のバイトのインデックス。</param>
        /// <param name="count">デコードするバイト数。</param>
        /// <returns>指定したバイト シーケンスのデコード結果が格納された文字配列。</returns>
        /// <exception cref="ArgumentNullException"><paremref name="bytes"/> が <c>null</c> です。</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> または <paremref name="count"/> が <c>0</c> 未満です。 または <paramref name="index"/> および <paramref name="count"/> が <paramref name="bytes"/> 内の有効な範囲を示していません。</exception>
        /// <exception cref="DecoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="DecoderFallback"/> が <see cref="DecoderExceptionFallback"/> に設定れています。 </exception>
        char[] GetChars(bool utf8Entry, byte[] bytes, int index, int count);

        /// <summary>指定したバイト配列に格納されているすべてのバイトを文字列にデコードします。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="bytes">デコード対象のバイト シーケンスが格納されたバイト配列。</param>
        /// <returns>指定したバイト シーケンスのデコード結果が格納されている<see cref="String"/>。</returns>
        /// <exception cref="ArgumentNullException"><paremref name="bytes"/> が <c>null</c> です。</exception>
        /// <exception cref="DecoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="DecoderFallback"/> が <see cref="DecoderExceptionFallback"/> に設定れています。 </exception>
        string GetString(bool utf8Entry, byte[] bytes);

        /// <summary>指定したバイト配列に格納されているバイト シーケンスを文字列にデコードします。</summary>
        /// <param name="utf8Entry">エントリのUTF-8フラグがオンであるかどうかを示す <see cref="Boolean"/> 値。</param>
        /// <param name="bytes">デコード対象のバイト シーケンスが格納されたバイト配列。</param>
        /// <param name="index">デコードする最初のバイトのインデックス。</param>
        /// <param name="count">デコードするバイト数。</param>
        /// <returns>指定したバイト シーケンスのデコード結果が格納される<see cref="String"/>。</returns>
        /// <exception cref="ArgumentNullException"><paremref name="bytes"/> が <c>null</c> です。</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> または <paremref name="count"/> が <c>0</c> 未満です。 または <paramref name="index"/> および <paramref name="count"/> が <paramref name="bytes"/> 内の有効な範囲を示していません。</exception>
        /// <exception cref="DecoderFallbackException">フォールバックが発生しました (詳細については、「エンコーディングの理解」を参照してください)。 および <see cref="DecoderFallback"/> が <see cref="DecoderExceptionFallback"/> に設定れています。 </exception>
        string GetString(bool utf8Entry, byte[] bytes, int index, int count);
    }
}
